看架構圖，可以知道現在有哪些元件。但我也會想知道：當初為什麼這樣選？有沒有考慮過別的方式？ADR，就是我想用來保留這些想法與取捨的紀錄。

本篇名詞小筆記

• ADR：架構決策紀錄（Architecture Decision Record），保存決策背景、選擇、影響與驗證方式。
• Context：決策當時的問題、限制與前提。
• Consequences：採用該決策後，需要接受的正面影響、成本與風險。
• Validation：用來確認決策是否達成預期效果的測試、指標或審查方式。

今天要解決的問題

開會時，大家可能比較過好幾個方案，也討論過各自的限制。但這些討論如果沒有寫下來，過一段時間，接手的人只看得到最後的選擇，很難分辨哪些是當初已經知道、也願意接受的代價，哪些是後來才出現的問題。

之後也可能有人再問一次「為什麼不用另一個方案」。如果能找回上次的理由與前提，只要確認這些前提現在還成不成立就好，不必從頭再討論一次。

架構師視角：最小可用的決策紀錄

# ADR-0XX：ERP 整合採 Adapter Service（示例）
Status: Accepted
Date: YYYY-MM-DD
Owner: 架構負責人
Review: 每 6 個月

## Context
ERP 對外只提供 SOAP，錯誤碼是 ERP 內部代碼；已有多個新服務需要寫入 ERP，也有服務要查詢 ERP 資料，查詢條件與可查範圍需要統一控管。

## Decision
寫入型 ERP 呼叫統一經過 Adapter；泛用查詢由查詢代理服務承接，業務服務都不直連 ERP。

## Consequences
增加一層延遲與維運成本；取得集中治理與契約隔離。

## Validation
禁止直連的架構測試、契約測試、P95 latency、故障演練。

欄位一多，寫的人容易填不完，讀的人也不容易抓到重點。所以我會先把這四節寫好，其他欄位等真的需要再加：Context 說明當時的問題與前提，Decision 記下最後的選擇，Consequences 寫下要接受的代價和換到的好處，Validation 則說明之後用什麼方式確認這個決策有沒有達到預期。

圖 Day 28-1：ADR 決策生命週期。

定期複核時，我會先確認原本的前提還成不成立。前提仍成立，就維持原來的決定；前提變了，再評估是不是需要新的決策。因為當初的前提有寫下來，所以要調整時，可以直接指出是哪一條前提變了。

ADR 的狀態可以用四種：Proposed 表示還在討論、尚未取得共識，Accepted 表示已經同意採用，Deprecated 表示不再建議採用，Superseded 表示已被新的 ADR 取代。因為之後有人問起時，要能同時找回當初的理由和後來為什麼改，所以舊 ADR 不刪除，只把狀態改成 Superseded，並註明由哪一份接手；新的 ADR 則在 Context 寫明是哪一條前提變了。

工程師視角：ADR 要接上程式碼與驗證

我希望改程式時，能順便確認原本的決定需不需要更新。所以我會把 ADR 放在 repository 裡一起版本控管，並連到 issue、PR、測試與架構圖。這樣改程式的 PR 可以同時修改相關的 ADR，Review 的人也能在同一份變更裡看到兩邊有沒有對上。

趕上線時，靠人記得去做的檢查最容易被跳過，所以 Validation 裡能變成自動檢查的項目，我會盡量放進測試或 CI。例如「業務服務不直連 ERP」可以寫成架構測試；契約可以用契約測試確認，P95 latency 則看監控或壓測結果。檢查跑過之後，再把結果和日期寫回 ADR 的 Validation，下次複核時就有依據。

架構圖說明現在長什麼樣子，ADR 說明為什麼長這樣，所以兩份文件會互相引用：圖旁標出相關的 ADR 編號，ADR 也連回對應的圖。兩份內容對不起來時，先確認是實作變了，還是文件沒改版。實作是刻意改的，就補一份新的 ADR；如果文件沒改版，就把圖或 ADR 更新到跟實作一致。

策略取捨與限制

要寫的東西少，才容易一直寫下去。所以一開始，可以先替影響大、難回復或跨團隊的決策寫 ADR，把 Context、Decision、Consequences、Validation 四節寫完整。如果比較過其他方案（也就是圖上的 Options），就順手記下來；之後真的需要更多資訊，再補欄位。

驗證方式與衡量指標

ADR 要在下一次討論時幫得上忙，得先有人寫，寫了能連到程式碼，之後也有人定期複核，所以我用這四項確認紀錄有沒有人在維護。為了知道之後由誰判斷、多久要複核一次，負責人和複核週期也要寫下來；它們不必另開一節，像 Status、Date 一樣在 ADR 開頭各寫一行就好。

今天先整理到這裡

把理由與前提寫下來之後，還要定期回頭確認實作和驗證結果是否符合當初的預期。像前一篇先選 Compose 的決定，就可以照這四節寫成一份 ADR，等多節點的需求出現時，再拿出來確認前提是不是變了。下一篇，再把 Validation 接到架構驗證、上線 SOP 與 Rollback，走完交付前的準備。

參考資料

1. Michael Nygard, Cognitect Blog, Documenting Architecture Decisions，查閱日期：2026-10-11。